home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / gui / bgui11b.lha / docs / commodityclass.doc < prev    next >
Encoding:
Text File  |  1994-09-26  |  6.9 KB  |  190 lines
  1.  
  2.            $RCSfile: commodityclass.doc,v $
  3.         Description: Commodityclass documentation.
  4.           Copyright: (C) Copyright 1994 Jaba Development.
  5.                      (C) Copyright 1994 Jan van den Baard.
  6.                      All Rights Reserved.
  7.  
  8.             $Author: jaba $
  9.           $Revision: 1.1 $
  10.               $Date: 1994/07/04 21:05:30 $
  11. ------------------------------------------------------------------------------
  12.  
  13. TABLE OF CONTENTS
  14.  
  15. commodityclass/--background--
  16. commodityclass/Methods
  17. commodityclass/Attributes
  18.  
  19. commodityclass/--background--                    commodityclass/--background--
  20.  
  21.     NAME
  22.         Class:          commodityclass
  23.         Superclass:     ROOTCLASS
  24.         Include File:   <libraries/bgui.h>
  25.  
  26.     FUNCTION
  27.         To  provide  a  BOOPSI based interface with the commodities.libraries.
  28.         This  class  will allow you to setup and maintain a simple broker with
  29.         simple  hotkeys.  The  attached hotkeys can also be seperatly disabled
  30.         and enabled.
  31.  
  32. commodityclass/Methods                                  commodityclass/Methods
  33.  
  34.     NEW METHODS
  35.         CM_ADDHOTKEY  --  This  method  must  be used to attach hotkeys to the
  36.                 broker. The following custom message structure is used:
  37.  
  38.                 struct cmAddHotKey {
  39.                         ULONG           MethodID; /* CM_ADDHOTKEY */
  40.                         STRPTR          cah_InputDescription;
  41.                         ULONG           cah_KeyID;
  42.                         ULONG           cah_Flags;
  43.                 };
  44.  
  45.                 cah_InputDescription -- This  must  point to a string in which
  46.                         the hotkey is described.  The input description string
  47.                         is the same string  as  you  would  pass  the HotKey()
  48.                         routine from the amiga.lib link library.
  49.  
  50.                 cah_KeyID -- This must be a 32Bit integer which represents the
  51.                         ID of the key.  This must be a unique value as this ID
  52.                         will be used to identify the key.
  53.  
  54.                 cah_Flags -- This  field  may have  any of the following flags
  55.                         set:
  56.  
  57.                         CAHF_DISABLED -- When  set  the  key  is  added to the
  58.                                 broker but it is disabled from usage.
  59.  
  60.                 The return code of this method will be  TRUE uppon success and
  61.                 FALSE uppon failure.
  62.  
  63.         CM_REMHOTKEY -- This method must be used to remove a hotkey.
  64.         CM_DISABLEHOTKEY -- This method must be used to disable a hotkey.
  65.         CM_ENABLEHOTKEY -- This method must be used to enable a hotkey.
  66.                 All three methods above use the same custom  message structure
  67.                 which is defined as follows:
  68.  
  69.                 struct cmDoKeyCommand {
  70.                         ULONG           MethodID; /* Any of the above. */
  71.                         ULONG           cdkc_KeyID;
  72.                 };
  73.  
  74.                 cdkc_KeyID -- This must be the ID of the key  which  was  used
  75.                         in the CM_ADDHOTKEY method.  When  the matching hotkey
  76.                         is found the appropiate action is taken.
  77.  
  78.                 The return code  of  these  methods will be TRUE uppon success
  79.                 and FALSE uppon failure.
  80.  
  81.         CM_ENABLEBROKER, CM_DISABLEBROKER -- These two methods must be used to
  82.                 switch the broker on or off.
  83.  
  84.         CM_MSGINFO -- This method must be used to  pull and  evaluate messages
  85.                 from the broker message port.  This method uses  the following
  86.                 custom message structure:
  87.  
  88.                 struct cmMsgInfo {
  89.                         ULONG           MethodID; /* CM_MSGINFO */
  90.                         struct {
  91.                                 ULONG  *Type;
  92.                                 ULONG  *ID;
  93.                                 ULONG  *Data;
  94.                         }               cm_Info;
  95.                 };
  96.  
  97.                 cm_Info -- This field can contain pointer to a storage  space
  98.                         which can  hold  32bits  each.  The  results  of  the
  99.                         CxMsgType(), CxMsgID() and CxMsgData() are  stored in
  100.                         here. When any of the storage fields is NULL  no data
  101.                         is stored.
  102.  
  103.                 This method will return CMMI_NOMORE  when  all messages  have
  104.                 been processed.
  105.  
  106.                 Example:
  107.  
  108.                 Object          *com_obj;
  109.                 ULONG            mask = 0, type, id, data, rc;
  110.                 BOOL             running = TRUE;
  111.  
  112.                 GetAttr( COMM_SigMask, com_obj, &mask );
  113.  
  114.                 do {
  115.                         Wait( mask );
  116.                         while (( rc = DoMethod( com_obj,
  117.                                                 CM_MSGINFO,
  118.                                                 &type,
  119.                                                 &id,
  120.                                                 &data )) != CMMI_NOMORE ) {
  121.                                 switch ( type ) {
  122.                                         ...
  123.                                 }
  124.                         }
  125.                 } while ( running );
  126.  
  127. commodityclass/Attributes                            commodityclass/Attributes
  128.  
  129.     NAME
  130.         COMM_Name -- ( STRPTR )
  131.         COMM_Title -- ( STRPTR )
  132.         COMM_Description -- ( STRPTR )
  133.         COMM_Priority -- ( LONG )
  134.         COMM_Unique -- ( BOOL )
  135.         COMM_Notify -- ( BOOL )
  136.         COMM_ShowHide -- ( BOOL )
  137.  
  138.     FUNCTION
  139.         These  attributes  correspond  to  the  fields  as  described  in  the
  140.         NewBroker structure from the <libraries/commodities.h> file. The three
  141.         boolean  attributes  can be used to set the NewBroker flags defined in
  142.         this same file.
  143.  
  144.         Defaults are as follows:
  145.                 COMM_Name               NULL
  146.                 COMM_Title              NULL
  147.                 COMM_Description        NULL
  148.                 COMM_Priority           0
  149.                 COMM_Unique             TRUE
  150.                 COMM_Notify             TRUE
  151.                 COMM_ShowHide           FALSE
  152.  
  153.         Applicability is (I).
  154.  
  155.     NAME
  156.         COMM_SigMask -- ( ULONG )
  157.  
  158.     FUNCTION
  159.         To  obtain  the  broker signal mask.
  160.  
  161.         Example:
  162.  
  163.         Object         *CO_Com;
  164.         ULONG           mask, sigrec;
  165.  
  166.         GetAttr( COMM_SigMask, CO_Com, &mask );
  167.  
  168.         do {
  169.                 sigrec = Wait( mask );
  170.                 ...
  171.         } while ( ... );
  172.  
  173.         Applicability is (G).
  174.  
  175.     NAME
  176.         COMM_ErrorCode -- ( ULONG )
  177.  
  178.     FUNCTION
  179.         To find out exactly what went wrong when adding a hotkey to the broker
  180.         failed.  Getting  this  attribute  can  result  in the following error
  181.         codes:
  182.  
  183.         CMERR_OK -- OK. No problems.
  184.         CMERR_NO_MEMORY -- Out of memory.
  185.         CMERR_KEYID_IN_USE -- Key ID was already used.
  186.         CMERR_KEY_CREATION -- Key creation failed.
  187.         CMERR_CXOBJERROR -- CxObjError() reported failure.
  188.  
  189.         Applicability is (G).
  190.